﻿---
title: "Builder basics"
---

Framework Builder works as an overlay of the running app; you edit your app while it's running. It gives you an accurate representation of what the app will look like and how it'll behave, without the need to constantly preview it. Changes to the user interface are automatically saved to `ui.json`.

## Modes

You can switch modes between _User Interface_, _Code_ and _Preview_ using the buttons on the top bar.

### User Interface

![Framework Builder - Mode: User Interface](/framework/images/builder-basics.ui.png#framework)

The default mode. Allows you to focus on building the interface.

### Code

![Framework Builder - Mode: Code](/framework/images/builder-basics.code.png#framework)

This mode displays the **code editor** and the **application log**, while still allowing you to access the _Component Tree_ and _Settings_.

<AccordionGroup>
  <Accordion title="Code editor">
    <Tip>
      Code changes are automatically detected. The application will reload whenever a change to a `.py` file inside the app folder is detected. This feature only works in Framework Builder i.e. `edit` mode, not when running the app in `run` mode.
    </Tip>
    The built-in code editor for `main.py`, the entry point of your application. This editor is provided for convenience and is ideal for quick edits — but you don't need to rely on it. If you need a more powerful editor or if your codebase is distributed across several files, use a local editor.
  </Accordion>
  <Accordion title="Application log">
    Exceptions raised by your application are shown here, as log entries. Standard output from your application is also captured and displayed as log entries.
  </Accordion>
</AccordionGroup>


### Preview

![Framework Builder - Mode: Preview](/framework/images/builder-basics.preview.png#framework)

The _Preview_ mode shows the application exactly like the user will see it. It allocates the whole width of the viewport to the app.

## Adding and moving components
You can create new components in your app by dragging and dropping items from the Toolkit. Some components, like Sections, can act as parents, while others, such as Text, cannot. Additionally, certain components have placement restrictions—for instance, a Column must be added to a Column Container, and a Sidebar can only be added to a Page. 

By default, components are positioned at the end, but if you need to place them specifically, simply drag them over the desired parent until you see the insertion lines. You can also reorganize existing components by moving them between parents or within the same parent. For more flexibility, the Component Tree can serve both as a source or a destination for your drag and drop actions.

## Selecting a component
Select a component by clicking on it. If you click on a component that's already selected, the click will be treated as an interaction with the app. Two things will happen when a component is selected:

<Steps>
  <Step title="Open component settings">
    The _Component Settings_ panel will open on the right. Depending on available screen real estate, the panel may open on top of the app or next to it.
  </Step>
  <Step title="Access component shortcuts">
    A set of component-specific actions, _Component Shortcuts_, will be displayed on top of the component.
  </Step>
</Steps>

## Component settings

Settings are divided into the following sections. Changes to settings can be undone and redone using the buttons on the top bar.

![Framework Builder - Component settings](/framework/images/builder-basics.component-settings.png)

<AccordionGroup>
  <Accordion title="Properties">
    Divided into _General_ and _Style_ categories. Values can include:
    1. Literals, e.g. `monkey`
    2. References to application state using the template syntax `@{}`, e.g. `@{my_favourite_animal}`.
    3. A combination of both, e.g. `My favourite animal is @{my_favourite_animal}`.
    4. Nested states can be accessed with `.` (dot), e.g. `@{building.height}`.
    5. Nested elements can be dynamically accessed with `[]`, e.g. `@{building[dynamic_prop]}` will be equivalent to `@{building.height}` when `dynamic_prop` equals `height`.
    Properties are of different types, such as _Text_, _Color_ and _Number_. All property values are stored as text values, then casted when being evaluated.
  </Accordion>
  <Accordion title="Binding">
    ![Framework Builder - Binding](/framework/images/builder-basics.binding.png)
    Input components can be bound, in a two-way fashion, to a state element.
    For example, a _Slider Input_ component can be bound to `my_var`. If the value of the slider changes, so does the value of `my_var`. Similarly, if the value of `my_var` changes, the slider is moved automatically to reflect the change.
    To bind an input component, specify the state element. For example, `my_var` or `building.height`. Note that this field should not contain the template syntax, e.g. `my_var` and not `@{my_var}`.
  </Accordion>
  <Accordion title="Events">
    The events generated by this component, with the option of setting event handlers for those. Event handlers are explained in more detail in a separate section of this guide.
  </Accordion>
  <Accordion title="Visibility">
    Whether the component should be displayed. There are three visibility options:
    1. Yes. The component is displayed.
    2. No. The component isn't displayed. Note that hidden components are still part of the HTML code but aren't shown.
    3. Custom. Whether the component is displayed or not depends on the value of a state or context element. For example, if set to `my_var`, visibility will depend on the value of the `my_var` state element. Note that this field, similarly to Binding, should only contain the state element, e.g. `my_var` and not `@{my_var}`.
  </Accordion>
</AccordionGroup>

## Component shortcuts

Perform a variety of operations on existing components. Options will be grayed out when they're not applicable to the relevant component. Most shortcuts can be triggered using the keyboard; hover on them to show the appropriate combination.

![Framework Builder - Component shortcuts](/framework/images/builder-basics.component-shortcuts.png)

<AccordionGroup>
  <Accordion title="Add">
    Adds a child of a specified type to this component.
  </Accordion>
  <Accordion title="Move Up">
    Decrements the position index of the component, used to sort children within the parent container.
  </Accordion>
  <Accordion title="Move Down">
    Increments the position index of the component.
  </Accordion>
  <Accordion title="Cut">
    Cuts the component and places it into Builder’s internal clipboard.
  </Accordion>
  <Accordion title="Copy">
    Copies the component and places it into the internal clipboard.
  </Accordion>
  <Accordion title="Paste">
    Pastes the content of the internal clipboard using the selected component as a parent.
  </Accordion>
  <Accordion title="Go to Parent">
    Selects the parent of the selected component.
  </Accordion>
  <Accordion title="Delete">
    Deletes this component.
  </Accordion>
</AccordionGroup>


Just like with changes to settings, these operations can be undone and redone.

## Discovering components

The Builder is designed to allow easy discoverability of components. Rather than scouring specifications every time you need to use a component, you can rely on the visual editor to guide you.

1. **Short description:** You can hover on the component type to get a tooltip with a short description.
2. **Available properties and events:** Looking at _Settings_ will allow you to see which of its properties are configurable.
3. **Built-in docs:** Components have short docs built into them. You can expand it by clicking the help icon in Settings.
4. **Event handler stub code:** Different events need to be handled differently. The built-in stub handlers, which can be found next to each event, can help you get started when writing event handlers.
